Resource API - WildFly Camel

Content

Resource

A Resource has an identity and associated Capabilities/Requirements.

A Resource stored in the Repository may provide binary content.

A Resource installed in an Environment may have an existing Wiring to other resources.

Here is what a simple resource looks like in XML representation

  <resource>
    <capability namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.apache.camel.camel.jmx" />
      <attribute name="maven.identity" value="org.apache.camel:camel-jmx:jar:2.11.0" />
      <attribute name="version" value="2.11.0" />
    </capability>
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="javax.api" />
    </requirement>
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="javax.xml.bind.api" />
      <attribute name="version" value="[2.2,3.0)" />
    </requirement>
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.apache.camel.core" />
      <attribute name="version" value="[2.11,2.11]" />
    </requirement>
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.slf4j" />
      <attribute name="version" value="[1.7,2.0)" />
    </requirement>
  </resource>

Resource Identity

A ResourceIdentity is defined by

symbolic name
version

The Version syntax and semantic is that of an OSGi version.

A resource identity can be constructed like this

ResourceIdentity.create("org.acme.foo", Version.parseVersion("1.0.0"));

ResourceIdentity.fromString("org.acme.foo:1.0.0"));

Capabilities

A Capability is associated with a Resource. It has

a namespace
attributes (optional)
directives (optional)

Attribute matching is described below. Capability directives are currently not used.

Identity Capability

Every Resource must have an identity Capability.

  <resource>
    <capability namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.acme.foo" />
      <attribute name="version" value="1.0.0" />
    </capability>
  </resource>

Gravia defines an IdentityNamespace that can be used with identity capabilities/requirements.

Requirements

A Requirement is associated with a Resource. It has

a namespace
attributes (optional)
directives (optional)

Identity Requirements

Resources may define requirements on other resources by identity.

  <resource>
    ...
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.acme.foo" />
      <attribute name="version" value="[1.0,2.0)" />
    </requirement>
  </resource>

The version attribute on an identity requirement must be give as a VersionRange. The version range syntax and semantic is that of an OSGi version range.

Attribute Matching

Requirement/Capability matching is abstracted by a MatchPolicy. The default implementation compares

namespaces
attributes

of the given capability/requirement. For attributes to match, every required attribute must have a match in the capability's set of attributes (i.e. a required version range must match the provided version).

Directives

Directives on a Requirement can give additional directive information to a layer that uses the Requirement. For example the Resolver can be informed that a give Requirement is optional for resolution.

  <resource>
    ...
    <requirement namespace="gravia.identity">
      <attribute name="gravia.identity" value="org.acme.foo" />
      <attribute name="version" value="[1.0,2.0)" />
      <directive name="resolution" value="optional" />
    </requirement>
  </resource>

Resource Building

Resource building is done via a ResourceBuilder. There are specialised versions that can build resources from manifest headers or resource XML definitions. Because of Gravia's generic resource definition it'd be easy to construct resources from other sources (i.e. Karaf feature file)

        ResourceBuilder builder = new DefaultResourceBuilder();
        builder.addIdentityCapability("resA", new Version("1.0.0"));
        builder.addIdentityRequirement("resB", new VersionRange("[1.0,2.0)"));
        Resource resource = builder.getResource();

        ManifestResourceBuilder builder = new ManifestResourceBuilder();
        Resource resource = builder.load(manifest).getResource();

Resource Store

A ResourceStore is the abstraction to store, find, iterate Resources. Perhaps most importantly, it can find Capability providers for a given Requirement.
The RepositoryStorage as well as the Environment are specialised versions of a ResourceStore.